home *** CD-ROM | disk | FTP | other *** search
/ DOpus Plus / DOpus Plus.iso / SDK / docs / ipc.doc < prev    next >
Encoding:
Text File  |  1998-10-26  |  11.1 KB  |  327 lines
  1. dopus5.library/IPC_Command                         dopus5.library/IPC_Command
  2.  
  3.     NAME
  4.         IPC_Command - send a command to an IPC process
  5.  
  6.     SYNOPSIS
  7.         IPC_Command(ipc, command, flags, data, data_free, reply)
  8.                      A0    D0      D1     A1      A2       A3
  9.  
  10.         ULONG IPC_Command(IPCData *, ULONG, ULONG, APTR, APTR,
  11.                           struct MsgPort *);
  12.  
  13.     FUNCTION
  14.         Sends a command to an IPC process. Can be used from a non-IPC
  15.         process but this is not recommended.
  16.  
  17.     INPUTS
  18.         ipc - IPC process to send command to
  19.  
  20.         command - command code (application-specific)
  21.  
  22.         flags - command flags (application-specific)
  23.  
  24.         data - command data (application-specific)
  25.  
  26.         data_free - additional data. The data specified here will be
  27.                     automatically freed with FreeVec() when the message
  28.                     is replied to, so you MUST allocate it with
  29.                     AllocVec().
  30.  
  31.         reply - reply port. You can either specify a message port for
  32.                 the reply, or use one of these special values :
  33.  
  34.                     REPLY_NO_PORT     - use default port for reply
  35.                     REPLY_NO_PORT_IPC - specify this if the message is sent
  36.                                         from a non-IPC process
  37.  
  38.                 If you don't want a reply to this message (ie you want it
  39.                 to be sent asynchronously), specify NULL for this value.
  40.  
  41.     RESULT
  42.         The command will be sent to the specified process. If the command
  43.         was not sent asynchronously, the destination process' result code
  44.         is returned.
  45.  
  46.     NOTES
  47.         There are several reserved command codes. You are free to use these
  48.         for your own applications, or use your own codes. These are listed
  49.         in <dopus/ipc.h>.
  50.  
  51.     SEE ALSO
  52.         IPC_Launch(), IPC_Reply()
  53.  
  54. dopus5.library/IPC_FindProc                       dopus5.library/IPC_FindProc
  55.  
  56.     NAME
  57.         IPC_FindProc - find an IPC process by name
  58.  
  59.     SYNOPSIS
  60.         IPC_FindProc(list, name, activate, data)
  61.                       A0    A1      D0      D1
  62.  
  63.         IPCData *IPC_FindProc(struct ListLock *, char *, BOOL, ULONG);
  64.  
  65.     FUNCTION
  66.         This routine searches the supplied list for a named IPC process.
  67.         Optionally, it can send this process an IPC_ACTIVATE message with
  68.         user-specified data.
  69.  
  70.     INPUTS
  71.         list - ListLock to search. This routine locks this list in shared
  72.                mode, and will block until the list is available.
  73.  
  74.         name - name to search for (case sensitive)
  75.  
  76.         activate - specify TRUE if you want an IPC_ACTIVATE message to be sent
  77.                    automatically.
  78.  
  79.         data - if 'activate' is TRUE, this value will be passed in the data
  80.                field of the IPC_ACTIVATE command.
  81.  
  82.     RESULT
  83.         If the process is found, its IPCData pointer is returned. To ensure
  84.         that this pointer remains valid you should Forbid(), or lock the
  85.         list yourself (in shared mode!).
  86.  
  87.     SEE ALSO
  88.         IPC_Launch(), IPC_Command()
  89.  
  90. dopus5.library/IPC_Flush                             dopus5.library/IPC_Flush
  91.  
  92.     NAME
  93.         IPC_Flush - flush an IPC command port
  94.  
  95.     SYNOPSIS
  96.         IPC_Flush(ipc)
  97.                    A0
  98.  
  99.         void IPC_Flush(IPCData *);
  100.  
  101.     FUNCTION
  102.         This routine searches the command port for any messages and replies
  103.         to them with an IPC_ABORT.
  104.  
  105.     INPUTS
  106.         ipc - IPCData of the process
  107.  
  108.     RESULT
  109.         The port is emptied.
  110.  
  111.     NOTES
  112.         In practice you rarely need this function.
  113.  
  114.     SEE ALSO
  115.         IPC_Free()
  116.  
  117. dopus5.library/IPC_Free                               dopus5.library/IPC_Free
  118.  
  119.     NAME
  120.         IPC_Free - free an IPC process
  121.  
  122.     SYNOPSIS
  123.         IPC_Free(ipc)
  124.                   A0
  125.  
  126.         void IPC_Free(IPCData *);
  127.  
  128.     FUNCTION
  129.         This routine frees all the memory associated with an IPC process
  130.         entry. It does NOT remove the process itself from the system. It is
  131.         designed to be called by a process on itself, as the last step before
  132.         exiting.
  133.  
  134.     INPUTS
  135.         ipc - IPCData to free
  136.  
  137.     RESULT
  138.         The IPCData handle is freed. If the process was a member of a list,
  139.         it is removed from that list. Any commands still in its message port
  140.         are replied to with IPC_ABORT.
  141.  
  142.     SEE ALSO
  143.         IPC_Launch()
  144.  
  145. dopus5.library/IPC_Launch                           dopus5.library/IPC_Launch
  146.  
  147.     NAME
  148.         IPC_Launch - launch a new process
  149.  
  150.     SYNOPSIS
  151.         IPC_Launch(list, ipcptr, name, entry, stack, data, doslib)
  152.                     A0     A1     A2     D0    D1     D2     A3
  153.  
  154.         long IPC_Launch(struct ListLock *, IPCData **, char *,
  155.                         ULONG, ULONG, ULONG, struct Library *);
  156.  
  157.     FUNCTION
  158.         The IPC routines in the dopus5.library provide an easy and efficient
  159.         way to implement multi-threading in your application. Using the
  160.         IPC_Launch functions creates an IPCData, which is a handle to a
  161.         process. Using this handle you can easily send command between
  162.         multiple processes.
  163.  
  164.         The important fields in the IPCData structure are as follows :
  165.  
  166.             proc            - pointer to the Process structure
  167.             command_port    - port to listen to for commands
  168.             userdata        - user-specified data
  169.             memory          - a memory pool you can use
  170.  
  171.         All Opus 5 modules are launched as IPC processes, and are passed
  172.         a pointer to their IPCData structures. They are also passed the
  173.         address of the main Directory Opus IPCData structure, which allows
  174.         them to send direct commands to Opus.
  175.  
  176.         If you are writing a standalone application and wish to use the IPC
  177.         routines, your main thread will need to create an IPCData structure
  178.         manually. It must be initialised as follows :
  179.  
  180.             proc            - pointer to your main Process
  181.             command_port    - pointer to a message port
  182.             list            - NULL
  183.             reply_port      - pointer to a DIFFERENT message port
  184.  
  185.         IPC processes can automatically be added to a list. There is no
  186.         need for you to keep track of a process once it has been launched,
  187.         except that your main process can't exit while a child is still
  188.         running (as the code would be freed).
  189.  
  190.     INPUTS
  191.         list - pointer to an initialise ListLock structure if you want this
  192.                process to be automatically added to a list (can be NULL).
  193.  
  194.         ipcptr - pointer to a pointer to IPCData. If the process is launched
  195.                  successfully, the new IPCData handle will be stored in this
  196.                  address (can be NULL).
  197.  
  198.         name - name for the new process.
  199.  
  200.         entry - pointer to code for the new process.
  201.  
  202.         stack - stack size for the new process. You can also set the
  203.                 IPCF_GETPATH flag in the stack variable, to have the new
  204.                 process automatically inherit the system path list.
  205.  
  206.         data - data that is automatically passed to the new process
  207.  
  208.         doslib - you must supply a pointer to the DOS library
  209.  
  210.     RESULT
  211.         This routine returns 0 if the child process failed to launch.
  212.         However, if the child process was actually launched, but failed
  213.         to initialise because of lack of memory, or a failure in your
  214.         user-defined initialisation code (see IPC_ProcStartup), the
  215.         return value will still indicate success.
  216.  
  217.         A better way to test failure is to specify a variable for the 'ipcptr'
  218.         parameter. If this is NULL after this call, the process failed to
  219.         start.
  220.  
  221.     SEE ALSO
  222.         IPC_ProcStartup(), IPC_Command(), IPC_Free
  223.  
  224. dopus5.library/IPC_ListCommand                 dopus5.library/IPC_ListCommand
  225.  
  226.     NAME
  227.         IPC_ListCommand - send a command to a list of processes
  228.  
  229.     SYNOPSIS
  230.         IPC_ListCommand(list, command, flags, data, wait)
  231.                          A0      D0      D1    D2    D3
  232.  
  233.         void IPC_ListCommand(struct ListLock *, ULONG, ULONG, ULONG, BOOL);
  234.  
  235.     FUNCTION
  236.         Sends the same command to every process on the supplied list.
  237.         Optionally waits for a reply from every process.
  238.  
  239.     INPUTS
  240.         list - list of processes
  241.         command - command ID to send
  242.         flags - command flags
  243.         data - command data
  244.         wait - specify TRUE if you want to wait for replies
  245.  
  246.     RESULT
  247.         The command is sent to every process on the list. If 'wait' is
  248.         TRUE, does not return until every process has replied.
  249.  
  250.     SEE ALSO
  251.         IPC_Launch(), IPC_Command()
  252.  
  253. dopus5.library/IPC_ProcStartup                 dopus5.library/IPC_ProcStartup
  254.  
  255.     NAME
  256.         IPC_ProcStartup - startup code for an IPC process
  257.  
  258.     SYNOPSIS
  259.         IPC_ProcStartup(data, code)
  260.                          A0    A1
  261.  
  262.         IPCData *IPC_ProcStartup(ULONG *, ULONG *);
  263.  
  264.     FUNCTION
  265.         Your IPC process should call this routine as the very first
  266.         instruction. It receives the startup message from the parent process,
  267.         and lets you retrieve your own IPCData handle.
  268.  
  269.     INPUTS
  270.         data - pointer to a variable to receive a pointer to the data that
  271.                was passed to IPC_Launch.
  272.  
  273.         code - address of a user-supplied initialisation routine to call. If
  274.                you provide this, your routine is called from this function.
  275.                The prototype of this routine is as follows :
  276.  
  277.                     ULONG __asm code(register __a0 IPCData *ipc,
  278.                                      register __a1 APTR data)
  279.  
  280.                Your intialisation routine receives a pointer to the IPCData
  281.                handle of the new process, and a pointer to the data passed
  282.                to IPC_Launch. This routine can do pretty much anything, but
  283.                you should keep it as simple as possible (there should
  284.                certainly be no IPC functions called from within it).
  285.                Your routine should return FALSE for failure and TRUE for
  286.                success. If it returns FALSE, the IPC_ProcStartup() call will
  287.                return NULL, and the new process should then quit.
  288.  
  289.     RESULT
  290.         Returns a pointer to your new IPCData handle. The 'data' value that
  291.         was passed to IPC_Launch() is stored in the supplied variable.
  292.         If this routine returns NULL, it means an error occurred (either in
  293.         the intialisation of the new process, or in your own initialisation
  294.         code). In this case, you should exit immediately.
  295.  
  296.     SEE ALSO
  297.         IPC_Launch()
  298.  
  299. dopus5.library/IPC_Reply                             dopus5.library/IPC_Reply
  300.  
  301.     NAME
  302.         IPC_Reply - reply to an IPC message
  303.  
  304.     SYNOPSIS
  305.         IPC_Reply(msg)
  306.                    A0
  307.  
  308.         void IPC_Reply(IPCMessage *);
  309.  
  310.     FUNCTION
  311.         Call this routine to reply to IPCMessages you receive at your
  312.         command port (do not call ReplyMsg())
  313.  
  314.     INPUTS
  315.         msg - message to reply
  316.  
  317.     RESULT
  318.         The message is replied. It is possible to pass a return code back
  319.         to the sending task (providing the message was sent synchronously).
  320.         To do this, set the 'command' field of the message to the value.
  321.         This will then be the return from the IPC_Command() function for the
  322.         other process.
  323.  
  324.     SEE ALSO
  325.         IPC_Launch(), IPC_Command()
  326.  
  327.